/*
 * Created by zhangzxiang91@gmail.com on 2021/09/23.
 */
package com.perfma.util.service;

import com.perfma.util.exception.StorageException;
import com.perfma.util.model.*;

import java.io.InputStream;

/**
 * @author zhangzxiang91@gmail.com
 * @date 2021/09/23.
 */
@SuppressWarnings("JavadocReference")
public interface StorageService {

    /**
     * 上传文件
     * <p>
     * 注意：[uploadFile、uploadStream、uploadBytes] 必须且只能设置一个
     * <p>
     * 参数说明：
     * {@link AppendUploadRequest#fileKey} 上传文件Key，如果未设置将自动生成一个fileKey
     * {@link AppendUploadRequest#uploadFile} 上传文件路径
     * {@link AppendUploadRequest#uploadBytes} 上传文件字节数据
     * {@link AppendUploadRequest#uploadStream} 上传文件输入流，仅支持最大Integer.MAX_VALUE(2G)的文件输出流上传，因为{@link InputStream#available()}最大只能表示Integer
     * * .MAX_VALUE大小的字节，对于大小超过2G的文件，建议通过{@link AppendUploadRequest#uploadFile}的方式上传
     */
    String upload(UploadRequest request) throws StorageException;

    /**
     * 追加上传文件
     * <p>
     * 注意：[uploadFile、uploadStream、uploadBytes] 必须且只能设置一个
     * <p>
     * 参数说明：
     * {@link AppendUploadRequest#fileKey} 追加上传文件Key，如果未设置将自动生成一个fileKey
     * {@link AppendUploadRequest#uploadFile} 上传文件路径
     * {@link AppendUploadRequest#uploadBytes} 上传文件字节数据
     * {@link AppendUploadRequest#uploadStream} 上传文件输入流，仅支持最大Integer.MAX_VALUE(2G)的文件输出流上传，因为{@link InputStream#available()}最大只能表示Integer
     * * .MAX_VALUE大小的字节，对于大小超过2G的文件，建议通过{@link AppendUploadRequest#uploadFile}的方式上传
     */
    @Deprecated
    String appendUpload(AppendUploadRequest request) throws StorageException;

    /**
     * 覆盖上传文件
     * <p>
     * 注意：[uploadFile、uploadStream、uploadBytes] 必须且只能设置一个
     * <p>
     * 参数说明：
     * {@link TruncateUploadRequest#fileKey} 覆盖上传文件Key，不能为空
     * {@link TruncateUploadRequest#uploadFile} 上传文件路径
     * {@link TruncateUploadRequest#uploadBytes} 上传文件字节数据
     * {@link TruncateUploadRequest#uploadStream} 上传文件输入流，仅支持最大Integer.MAX_VALUE(2G)的文件输出流上传，因为{@link InputStream#available()}最大只能表示Integer
     * * .MAX_VALUE大小的字节，对于大小超过2G的文件，建议通过{@link TruncateUploadRequest#uploadFile}的方式上传
     *
     * @deprecated By {@link #upload(UploadRequest)}
     */
    @Deprecated
    void truncateUpload(TruncateUploadRequest request) throws StorageException;

    /**
     * 下载文件
     * <p>
     * 注意：[outputFile、outputStream] 必须且只能设置一个
     * <p>
     * 参数说明：
     * {@link DownloadRequest#fileKey} 下载文件Key，不能为空
     * {@link DownloadRequest#offset} 文件下载的起始位置
     * {@link DownloadRequest#length} 文件下载的长度
     * {@link DownloadRequest#outputFile} 下载文件本地保存路径
     * {@link DownloadRequest#outputStream} 下载文件输出流，输出流需要调用方自己关闭
     *
     * @return 下载字节数
     */
    long download(DownloadRequest request) throws StorageException;

    /**
     * 删除文件，如果删除失败抛出异常
     *
     * @param fileKey 文件Key
     */
    void deleteFile(String fileKey) throws StorageException;

    /**
     * 查询文件信息，如果查询失败抛出异常
     *
     * @param fileKey 文件Key
     * @return 文件信息，如果文件不存在则返回NULL
     */
    FileInfo getFileInfo(String fileKey) throws StorageException;
}
